
package org.codehaus.janino.util.resource;

import org.codehaus.janino.Resource;
import java.io.IOException;
import java.io.InputStream;

/**
 * Finds a resource by name.
 * <p>
 * Notice that there is a symmetrical concept
 * {@link org.codehaus.janino.util.resource.ResourceCreator} that creates resources for
 * writing.
 *
 * @see org.codehaus.janino.util.resource.ResourceCreator
 */
public abstract class ResourceFinder {

    /**
     * Find a resource by name and open it for reading.
     *
     * @param resourceName Designates the resource; typically structured by slashes ("/") like
     *                     "<code>com/foo/pkg/Bar.class</code>"
     * @return             <code>null</code> if the resource could not be found
     * @throws IOException The resource was found, but there are problems opening it
     */
    public InputStream findResourceAsStream(String resourceName) throws IOException {
        Resource resource = this.findResource(resourceName);
        if (resource == null) {
            return null;
        }
        return resource.open();
    }

    /**
     * Find a resource by name and return it as a {@link Resource} object.
     *
     * @param resourceName Designates the resource; typically structured by slashes ("/") like
     *                     "<code>com/foo/pkg/Bar.class</code>"
     * @return             <code>null</code> if the resource could not be found
     */
    public abstract Resource findResource(String resourceName);

    /**
     * This one's useful when a resource finder is required, but cannot be created
     * for some reason.
     */
    public static final ResourceFinder EMPTY_RESOURCE_FINDER = new ResourceFinder() {
        public Resource findResource(String resourceName) { return null; }
        public String toString() { return "invalid entry"; }
    };
}
